home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / ODF Release 3 / Documentation / Engineering Notes / OpenDoc 1.1 vs. 1.2 < prev    next >
Encoding:
Text File  |  1996-12-13  |  6.1 KB  |  47 lines  |  [TEXT/ttxt]

  1. OpenDoc
  2. Development
  3. Framework
  4.                                                                                                                                                                                           
  5. OpenDoc 1.1 vs 1.2 
  6. ODF Release 3                                                                                                                                                                  
  7.  
  8.  
  9. OpenDoc Frame 'moving' semantics and ODF
  10.  
  11. An important optimization in OpenDoc is that when embedded content is cut and pasted, or dragged and dropped, the unnecessary cloning of embedded content is avoided.  The method for doing this in OpenDoc is undergoing a fundamental change as of OpenDoc 1.2.
  12.  
  13. Through OpenDoc 1.1, when cutting and pasting, or dragging and dropping content including one or more embedded frames, the cloning process  for obtaining a frame to embed at the drop or paste destination was short-circuited by OpenDoc, returning the ID of the the original moved frame, rather than that of a cloned copy.  
  14.  
  15. This optimization forced the introdcution of the In–Limbo flag and the rather complex recipes associated with it in order to ensure that an embedded frame hierarchy that had been removed from part content  would NOT be disassembled (by calling ODFrame::Removed) when it was, or could become embedded in another part, via undoing or redoing some action.  
  16.  
  17. In OpenDoc 1.2, when the container embedding the drop or the paste asks to clone the frame referenced in the data transfer storage unit, instead of returning the id for the original frame, OpenDoc 1.2 will create a new display frame for the existing part.  This incurs the additional overhead of propagating a new display frame hierarchy through the existing part hierarchy, but does not incur the potentially much larger cost of duplicating each embedded part's content.
  18.  
  19. Most importantly, it insures that a given embedded frame is owned solely by the part in which it is embedded.  Though the 'in limbo' flag of the ODFrame is still maintained, for backwards compatibility with code written to earlier versions of OpenDoc, the complex decision-making based upon its present and past value, and other factors will no longer be required.  Existing code which handles the pre-1.2 requirements correctly, or even mostly correctly, should function properly under 1.2, because the various special cases for which calling ODFrame::Removed was contraindicated, simply won't occur.
  20.  
  21. ODF R3 and Part Issues.
  22.  
  23. The new OpenDoc semantics for part moving make use of the AttachSourceFrame ODPart API in a way which violated certain assumptions that had been made in ODF.  A correction for ODF R2 was provided as a set of patch files.  The document which was provided with them (FWPart Update for OpenDoc 1.2) provides additional detail on the changes in both OpenDoc and ODF.
  24.  
  25. OpenDoc 1.1 compatibility
  26.  
  27. ODF R3  corrects certain problems in the handling of the In-Limbo flag under earlier versions of OpenDoc.  In order to handle all cases correctly, ODF parts that embed AND which need to be compatible with pre-1.2 versions of OpenDoc, are required to call the new FW_MProxy::CommitPasteDone method from overrides of FW_CDropCommand::FreeUndoState, and FW_CClipboardCommand::FreeUndoState, the latter only when the command is a paste or paste-as. The method is invoked on each embedded proxy involved in the drop or paste.
  28.  
  29. The Draw, Container, Table, and Embed examples all do this.  In all but the last, we found it quite helpful to introduce reference counting of content elements.  When content which has been dropped or pasted is subsequently cut or cleared or otherwise removed, this insures that the content objects won't be deleted by the command that removed them prior to being de-referenced in the FreeUndoState method of the command that added them in the first place.
  30.  
  31. We got away without reference counting before because it had been unnecessary to implement FreeUndoState for commands that added content.  In implementing these changes in the example parts, we found reference counting to be a pretty good idea anyway.  Given the fact of multiple undo/redo, it makes a lot of sense in any but the most rudimentary content models (e.g. ODFEmbed).
  32.  
  33. The two linking ODF parts, Table and Draw, do not yet handle every case correctly when link updates are involved.  To do so would require that a drag, cut, or clear command involving a link destination acquire references to the linked content in order to protect it from being prematurely disposed during a link update.  Not difficult to do, just not done yet.
  34.  
  35. OpenDoc 1.2 compatibility
  36.  
  37. In general, parts should not need any modifications for compatibility with OpenDoc 1.2.  None were required in any of the ODF example parts.  There are a few general caveats regarding this:
  38.  
  39. •  FW_CFrame::GetSourceFrame:  This method has been fixed up to transparently handle the differences in OpenDoc 1.2.  It is currently called by FW_CCommand as a result of user interaction within the frame.  If called by part code during the process of moving the frame upon which it is being called, an assertion may fail, and the resultant FW_CFrame may not be an appropriate choice for future use.  
  40.  
  41. In general, a value returned by GetSourceFrame may not remain valid indefinitely.  However, in particular, the value stored in an FW_CCommand will be valid whenever the command is undone or redone, though it may not be valid at all times between those calls.
  42.  
  43. • A second effect, whose actual impact has not been noticed and whose possible impact has not been fully analyzed, is the fact that under OpenDoc 1.2 it will be common for parts to have some display frames which are 'in limbo' while it is still visible and accessible for user interaction in others.  This has always been theoretically possible, but existing sample and test parts have never done anything to create this situation.  This heretofore untested case for embedded parts will be commonplace under OpenDoc 1.2.
  44.  
  45.  
  46. © 1993 - 1996 Apple Computer, Inc. All rights reserved.
  47. Apple, the Apple Logo, Macintosh, and OpenDoc are trademarks of Apple Computer, Inc., registered in the United States and other countries.